Skip to content

fix(onboard): use sudo lsof fallback to identify root-owned port blockers (fixes #726)#745

Merged
cv merged 3 commits intoNVIDIA:mainfrom
kagura-agent:fix/lsof-sudo-hint
Mar 31, 2026
Merged

fix(onboard): use sudo lsof fallback to identify root-owned port blockers (fixes #726)#745
cv merged 3 commits intoNVIDIA:mainfrom
kagura-agent:fix/lsof-sudo-hint

Conversation

@kagura-agent
Copy link
Copy Markdown
Contributor

@kagura-agent kagura-agent commented Mar 23, 2026 •
edited by coderabbitai bot
Loading

Fixes #726

Problem

When a non-root user runs NemoClaw onboarding and port 8080 is occupied by a root-owned process (e.g., docker-proxy, leftover gateway), lsof returns empty output because non-root users cannot see root-owned listeners. The preflight falls through to the net probe which detects EADDRINUSE but cannot identify the blocking process. The user sees:

Could not identify the process using port 8080.
Run: lsof -i :8080 -sTCP:LISTEN

Running that command also returns empty without sudo, leaving the user stuck.

Solution

  1. preflight.js: When regular lsof returns empty, automatically retry with sudo lsof to identify root-owned listeners before falling through to the net probe. This gives users actionable process info (name + PID) instead of a generic EADDRINUSE message.

  2. onboard.js: Update the user-facing hint to suggest sudo lsof instead of plain lsof.

Testing

All existing preflight tests pass (9/9). The sudo fallback is skipped when lsofOutput is injected (test mode), so no test changes needed.

Summary by CodeRabbit

  • Bug Fixes
    • Enhanced port availability detection with improved error reporting, now providing process and identifier information when port conflicts are detected.

fix(onboard): use sudo lsof fallback to identify root-owned port bloc…
993f562 
…kers (fixes NVIDIA#726)

Non-root users cannot see root-owned listeners with lsof, causing the
onboard preflight to fall through to the net probe which can only report
EADDRINUSE without process details. Users then see a generic 'Could not
identify the process' message suggesting 'lsof -i :PORT' which also
returns empty without sudo.

Changes:
- preflight.js: When lsof returns empty, retry with 'sudo lsof' to
  identify root-owned listeners (e.g., docker-proxy, leftover gateway)
  before falling through to the net probe
- onboard.js: Update the user-facing hint to suggest 'sudo lsof'
  instead of plain 'lsof'
@coderabbitai
Copy link
Copy Markdown
Contributor

coderabbitai bot commented Mar 23, 2026 •
edited
Loading

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info
⚙️ Run configuration

Configuration used: Path: .coderabbit.yaml

Review profile: CHILL

Plan: Pro

Run ID: 16b8125d-2e6c-4466-9c15-c5ca8c47a1f8

📥 Commits

Reviewing files that changed from the base of the PR and between 79d1d78 and f22e524.

📒 Files selected for processing (1)
  • bin/lib/preflight.js
🚧 Files skipped from review as they are similar to previous changes (1)
  • bin/lib/preflight.js
📝 Walkthrough

Walkthrough

The checkPortAvailable function in bin/lib/preflight.js now attempts to run sudo lsof when the standard lsof command returns no process data. If sudo lsof yields usable results, the function extracts and reports the process details; otherwise, it falls back to existing net probe behavior.

Changes

Cohort / File(s) Summary
Port detection enhancement
bin/lib/preflight.js		 Added fallback to sudo lsof when standard lsof -i :<port> produces no data rows. Parses first data row to extract process name and PID, returning detailed error information. If sudo lsof also yields no data, preserves original net probe fallback behavior.

Estimated code review effort

🎯 2 (Simple) | ⏱️ ~12 minutes

Poem

🐰 With whiskers twitched and paws held high,
We probe the ports with sudo's sigh,
When lsof speaks not plain and clear,
Root access makes the process near! 🔑

🚥 Pre-merge checks | ✅ 5
✅ Passed checks (5 passed)
Check name Status Explanation
Description Check ✅ Passed Check skipped - CodeRabbit’s high-level summary is enabled.
Title check ✅ Passed The PR title clearly and specifically describes the main change: implementing a sudo lsof fallback to identify root-owned port blockers in the onboarding preflight checks, with direct reference to the fixed issue.
Linked Issues check ✅ Passed The code changes fully address the linked issue #726 by implementing sudo lsof fallback detection for root-owned listeners and improving user-facing hints with process identification before net probe fallback.
Out of Scope Changes check ✅ Passed All changes in bin/lib/preflight.js are directly scoped to implementing the sudo lsof fallback logic required by issue #726, with no extraneous modifications detected.
Docstring Coverage ✅ Passed Docstring coverage is 100.00% which is sufficient. The required threshold is 80.00%.

✏️ Tip: You can configure your own custom pre-merge checks in the settings.

✨ Finishing Touches
🧪 Generate unit tests (beta)
  • Create PR with unit tests

Comment @coderabbitai help to get the list of available commands and usage tips.

@wscurran wscurran added bug Something isn't working Getting Started Use this label to identify setup, installation, or onboarding issues. labels Mar 24, 2026
@wscurran
Copy link
Copy Markdown
Contributor

wscurran commented Mar 24, 2026

Thanks for submitting this PR, it improves the onboarding process by using sudo lsof fallback to identify root-owned port blockers, which could improve the user experience and prevent potential issues for new users.

@kagura-agent
Copy link
Copy Markdown
Contributor Author

kagura-agent commented Mar 25, 2026

Thank you for the review, @wscurran! Happy to help improve the onboarding experience.

@wscurran wscurran mentioned this pull request Mar 25, 2026
Closed
2 tasks
@kagura-agent
Copy link
Copy Markdown
Contributor Author

kagura-agent commented Mar 30, 2026

Gentle ping — this has been open for a week. Let me know if there's anything to adjust. Will close in 7 days if no response. 🙏

1 similar comment
@kagura-agent
Copy link
Copy Markdown
Contributor Author

kagura-agent commented Mar 30, 2026

Gentle ping — this has been open for a week. Let me know if there's anything to adjust. Will close in 7 days if no response. 🙏

@cv cv merged commit f6b7705 into NVIDIA:main Mar 31, 2026
1 check passed
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Reviewers

@cv cv cv approved these changes

Assignees

No one assigned

Labels

bug Something isn't working Getting Started Use this label to identify setup, installation, or onboarding issues.

Projects

None yet

Milestone

No milestone

Development

Successfully merging this pull request may close these issues.

lsof -i:8080 command on onboarding needs sudo prefix to work properly

3 participants

@kagura-agent @wscurran @cv